SGI Freeware 1999 August/SGI Freeware 1999 August.iso/dist/fw_xemacs.idb/usr/freeware/lib/xemacs-20.4/info/vhdl-mode.info.z/vhdl-mode.info

GNU Info File | 1998-05-21 | 41.1 KB | 1,044 lines

This is Info file ../info/vhdl-mode.info, produced by Makeinfo version
1.68 from the input file vhdl-mode.texi.

   Copyright (C) 1995 - 1997 Rodney J. Whitby <[e-mail]>


File: vhdl-mode.info,  Node: Top,  Next: Introduction,  Prev: (dir),  Up: (dir)

* Menu:

* Introduction::
* Getting Connected::
* New Indentation Engine::
* Customizing Indentation::
* Syntactic Symbols::
* Indentation Commands::
* Frequently Asked Questions::
* Getting the latest vhdl-mode release::
* Sample .emacs File::
* Requirements::
* Limitations and Known Bugs::
* Mailing Lists and Submitting Bug Reports::
* Concept Index::
* Command Index::               Command Index
* Key Index::                   Key Index
* Variable Index::              Variable Index


File: vhdl-mode.info,  Node: Introduction,  Next: Getting Connected,  Prev: Top,  Up: Top

Introduction
************

   Welcome to `vhdl-mode', version 2.  This is a GNU Emacs mode for
editing files containing VHDL code.

   This manual will describe the following:

   * How to get started using `vhdl-mode'.

   * How the new indentation engine works.

   * How to customize the new indentation engine.

   The major version number was incremented to 2 with the addition of
the new indentation engine. To find the minor revision number of this
release, use `M-x vhdl-version RET'.

   A special word of thanks goes to Barry Warsaw, who wrote the
`cc-mode' indentation engine that formed the basis of the `vhdl-mode'
indentation engine.  This manual is also based upon the manual for
`cc-mode'.


File: vhdl-mode.info,  Node: Getting Connected,  Next: New Indentation Engine,  Prev: Introduction,  Up: Top

Getting Connected
*****************

   `vhdl-mode.el' works well with the 3 main branches of Emacs 19:
XEmacs, Win-Emacs (which has the same heritage as XEmacs) and the Emacs
19 maintained by the FSF.  FSF's Emacs 19 users will want to use Emacs
version 19.21 or better, Win-Emacs users will want 1.35 or better, and
XEmacs users will want 19.6 or better.  Earlier versions of these
Emacsen have deficiencies and/or bugs which will adversely affect the
performance and usability of `vhdl-mode'.

   The first thing you will want to do is put `vhdl-mode.el' somewhere
on your `load-path' so Emacs can find it.  Do a `C-h v load-path RET'
to see all the directories Emacs looks at when loading a file.  If none
of these directories are appropriate, create a new directory and add it
to your `load-path':

*[in the shell]*

     % cd
     % mkdir mylisp
     % mv vhdl-mode.el mylisp
     % cd mylisp

*[in your .emacs file add]*

     (setq load-path (cons "~/mylisp" load-path))

   Next you want to "byte compile" `vhdl-mode.el'.  The mode uses a lot
of macros so if you don't byte compile it, things will be unbearably
slow.  *You can ignore all byte-compiler warnings!*  They are the
result of the supporting different versions of Emacs, and none of the
warnings have any effect on operation. Let me say this again: *You
really can ignore all byte-compiler warnings!*

   Here's what to do to byte-compile the file [in emacs]:

     M-x byte-compile-file RET ~/mylisp/vhdl-mode.el RET

   Now add the following autoloads to your `.emacs' file so that
`vhdl-mode' gets loaded at the right time:

     (autoload 'vhdl-mode "vhdl-mode" "VHDL Editing Mode" t)

   Alternatively, if you want to make sure `vhdl-mode' is loaded when
Emacs starts up, you could use this line instead of the autoload above:

     (require 'vhdl-mode)

   Next, you will want to set up Emacs so that it edits VHDL files in
`vhdl-mode'. All users should add the following to their `.emacs' file.
Note that this assumes you'll be editing `.vhd' and files as VHDL.
YMMV:

     (setq auto-mode-alist
       (append
         '(("\\.vhd$" . vhdl-mode)
          ) auto-mode-alist))

   That's all you need - I know, I know, it sounds like a lot `:-)',
but after you've done all this, you should only need to quit and restart
Emacs.  The next time you visit a VHDL file you should be using
`vhdl-mode'.  You can check this easily by hitting `M-x vhdl-version
RET' in the `vhdl-mode' buffer.  You should see this message in the
echo area:

     Using `vhdl-mode' version 2.XXX

where XXX will be some minor revision number.


File: vhdl-mode.info,  Node: New Indentation Engine,  Next: Indentation Commands,  Prev: Getting Connected,  Up: Top

New Indentation Engine
**********************

   `vhdl-mode' has a new indentation engine, providing a simplified, yet
flexible and general mechanism for customizing indentation. It breaks
indentation calculation into two steps. First for the line of code being
indented, `vhdl-mode' analyzes what kind of language construct it's
looking at, then it applies user defined offsets to the current line
based on this analysis.

   This section will briefly cover how indentation is calculated in
`vhdl-mode'. It is important to understand the indentation model being
used so that you will know how to customize `vhdl-mode' for your
personal coding style.

* Menu:

* Syntactic Analysis::       Step 1 - Syntactic Analysis
* Indentation Calculation::  Step 2 - Indentation Calculation


File: vhdl-mode.info,  Node: Syntactic Analysis,  Next: Indentation Calculation,  Up: New Indentation Engine

Syntactic Analysis
==================

   The first thing `vhdl-mode' does when indenting a line of code, is
to analyze the line, determining the "syntactic component list" of the
construct on that line.  A "syntactic component" consists of a pair of
information (in lisp parlance, a *cons cell*), where the first part is
a "syntactic symbol", and the second part is a "relative buffer
position".  Syntactic symbols describe elements of VHDL code, e.g.
`statement', `comment', `block-open', `block-close', etc.  *Note
Syntactic Symbols::, for a complete list of currently recognized
syntactic symbols and their semantics.  Also, the variable
`vhdl-offsets-alist' contains the list of currently supported syntactic
symbols.

   Conceptually, a line of VHDL code is always indented relative to the
indentation of some line higher up in the buffer.  This is represented
by the relative buffer position in the syntactic component.

   It might help to see an example. Suppose we had the following code as
the only thing in a `vhdl-mode' buffer (1):

       1: inverter : process
       2: begin
       3:   q <= not d;
       4:   wait on d;
       5: end inverter;

   We can use the command `C-c C-s' (`vhdl-show-syntactic-information')
to simply report what the syntactic analysis is for the current line.
Running this command on line 4 of example 1, we'd see in the echo area:

     ((statement . 28))

   This tells us that the line is a statement and it is indented
relative to buffer position 28, which happens to be the `q' on line 3.
If you were to move point to line 3 and hit `C-c C-s', you would see:

     ((statement-block-intro . 20))

   This indicates that line 3 is the first statement in a block, and is
indented relative to buffer position 20, which is the `b' in the
`begin' keyword on line 2.

   Syntactic component lists can contain more than one component, and
individual syntactic compenents need not have relative buffer positions.
The most common example of this is a line that contains a "comment only
line".

     %%% TBD %%%

Hitting `C-c C-s' on line 3 of the example gives us:

     ((comment-intro) (block-intro . 46))

so you can see that the syntactic component list contains two syntactic
components.  Also notice that the first component, `(comment-intro)'
has no relative buffer position.

   ---------- Footnotes ----------

   (1) The line numbers in this and future examples don't actually
appear in the buffer.


File: vhdl-mode.info,  Node: Indentation Calculation,  Prev: Syntactic Analysis,  Up: New Indentation Engine

Indentation Calculation
=======================

   Indentation for the current line is calculated using the syntactic
component list derived in step 1 above (see *Note Syntactic
Analysis::).  Each component contributes to the final total indentation
of the line in two ways.

   First, the syntactic symbols are looked up in the
`vhdl-offsets-alist' variable, which is an association list of
syntactic symbols and the offsets to apply for those symbols.  These
offsets are added to the running total.

   Second, if the component has a relative buffer position, `vhdl-mode'
adds the column number of that position to the running total.  By adding
up the offsets and columns for every syntactic component on the list,
the final total indentation for the current line is computed.

   Let's use our code example above to see how this works.  Here is our
example again.

       1: inverter : process
       2: begin
       3:   q <= not d;
       4:   wait on d;
       5: end inverter;

   Let's say point is on line 3 and we hit the <TAB> key to re-indent
the line.  Remember that the syntactic component list for that line is:

     ((statement-block-intro . 20))

`vhdl-mode' looks up `statement-block-intro' in the
`vhdl-offsets-alist' variable.  Let's say it finds the value `2'; it
adds this to the running total (initialized to zero), yielding a
running total indentation of 2 spaces.

   Next `vhdl-mode' goes to buffer position 20 and asks for the current
column.  Since the `begin' keyword at buffer position 20 is in column
zero, it adds `0' to the running total.  Since there is only one
syntactic component on the list for this line, indentation calculation
is complete, and the total indentation for the line is 2 spaces.
Simple, huh?

   Actually, the mode usually just does The Right Thing without you
having to think about it in this much detail.  But when customizing
indentation, it's helpful to understand the general indentation model
being used.

   To help you configure `vhdl-mode', you can set the variable
`vhdl-echo-syntactic-information-p' to non-`nil' so that the syntactic
component list and calculated offset will always be echoed in the
minibuffer when you hit `TAB'.


File: vhdl-mode.info,  Node: Indentation Commands,  Next: Customizing Indentation,  Prev: New Indentation Engine,  Up: Top

Indentation Commands
********************

   *<TBD>*


File: vhdl-mode.info,  Node: Customizing Indentation,  Next: Syntactic Symbols,  Prev: Indentation Commands,  Up: Top

Customizing Indentation
***********************

   The `vhdl-offsets-alist' variable is where you customize all your
indentations.  You simply need to decide what additional offset you want
to add for every syntactic symbol.  You can use the command `C-c C-o'
(`vhdl-set-offset') as the way to set offsets, both interactively and
from your mode hook.  Also, you can set up *styles* of indentation.
Most likely, you'll find one of the pre-defined styles will suit your
needs, but if not, this section will describe how to set up basic
editing configurations.  *Note Styles:: for an explanation of how to
set up named styles.

   As mentioned previously, the variable `vhdl-offsets-alist' is an
association list between syntactic symbols and the offsets to be applied
for those symbols.  In fact, these offset values can be an integer, a
function or variable name, or one of the following symbols: `+', `-',
`++', `--', `*', or `/'.  The symbol values have the following meanings:

   * `+'  -  1 x `vhdl-basic-offset'

   * `-'  -  -1 x `vhdl-basic-offset'

   * `++' -  2 x `vhdl-basic-offset'

   * `--' -  -2 x `vhdl-basic-offset'

   * `*'  -  0.5 x `vhdl-basic-offset'

   * `/'  -  -0.5 x `vhdl-basic-offset'

So, for example, because most of the default offsets are defined in
terms of `+', `-', and `0', if you like the general indentation style,
but you use 2 spaces instead of 4 spaces per level, you can probably
achieve your style just by changing `vhdl-basic-offset' like so (in
your `.emacs' file):

     (setq vhdl-basic-offset 2)

   To change indentation styles more radically, you will want to change
the value associated with the syntactic symbols in the
`vhdl-offsets-alist' variable.  First, I'll show you how to do that
interactively, then I'll describe how to make changes to your `.emacs'
file so that your changes are more permanent.

* Menu:

* Interactive Customization::
* Permanent Customization::
* Styles::
* Advanced Customizations::


File: vhdl-mode.info,  Node: Interactive Customization,  Next: Permanent Customization,  Up: Customizing Indentation

Interactive Customization
=========================

   As an example of how to customize indentation, let's change the
style of the example above from:

       1: inverter : process
       2: begin
       3:   q <= not d;
       4:   wait on d;
       5: end inverter;

to:

       1: inverter : process
       2: begin
       3:     q <= not d;
       4:     wait on d;
       5: end inverter;

   In other words, we want to change the indentation of the statments
inside the inverter process.  Notice that the construct we want to
change starts on line 3.  To change the indentation of a line, we need
to see which syntactic component affect the offset calculations for that
line.  Hitting `C-c C-s' on line 3 yields:

     ((statement-block-intro . 20))

So we know that to change the offset of the first signal assignment, we
need to change the indentation for the `statement-block-intro' syntactic
symbol.  To do this interactively, just hit `C-c C-o'
(`vhdl-set-offset').  This prompts you for the syntactic symbol to
change, providing a reasonable default.  In this case, the default is
`statement-block-intro', which is just the syntactic symbol we want to
change!

   After you hit return, `vhdl-mode' will then prompt you for the new
offset value, with the old value as the default.  The default in this
case is `+', so hit backspace to delete the `+', then hit `++' and
`RET'.  This will associate an offset of twice the basic indent with
the syntactic symbol `statement-block-intro' in the
`vhdl-offsets-alist' variable.

   To check your changes quickly, just hit `C-c C-q'
(`vhdl-indent-defun') to reindent the entire function.  The example
should now look like:

       1: inverter : process
       2: begin
       3:     q <= not d;
       4:     wait on d;
       5: end inverter;

   Notice how just changing the offset on line 3 is all we needed to do.
Since the other affected lines are indented relative to line 3, they are
automatically indented the way you'd expect.  For more complicated
examples, this may not always work.  The general approach to take is to
always start adjusting offsets for lines higher up in the file, then
re-indent and see if any following lines need further adjustments.


File: vhdl-mode.info,  Node: Permanent Customization,  Next: Styles,  Prev: Interactive Customization,  Up: Customizing Indentation

Permanent Indentation
=====================

   To make this change permanent, you need to add some lisp code to your
`.emacs' file.  `vhdl-mode' provides a `vhdl-mode-hook' that you can
use to customize your language editing styles.  This hook gets run as
the last thing when you enter `vhdl-mode'.

   Here's a simplified example of what you can add to your `.emacs'
file to make the changes described in the previous section (*Note
Interactive Customization::) more permanent.  See the Emacs manuals for
more information on customizing Emacs via hooks.  *Note Sample .emacs
File:: for a more complete sample `.emacs' file.  (1)

     (defun my-vhdl-mode-hook ()
       ;; my customizations for all of vhdl-mode
       (vhdl-set-offset 'statement-block-intro '++)
       ;; other customizations can go here
       )
     (add-hook 'vhdl-mode-hook 'my-vhdl-mode-hook)

   For complex customizations, you will probably want to set up a
*style* that groups all your customizations under a single name. *Note
Styles:: for details.

   The offset value can also be a function, and this is how power users
gain enormous flexibility in customizing indentation. *Note Advanced
Customizations:: for details.

   ---------- Footnotes ----------

   (1) The use of `add-hook' in this example only works for Emacs 19.
Workarounds are available if you are using Emacs 18, but this just
points out another reason for you to upgrade to Emacs 19!  `:-)'


File: vhdl-mode.info,  Node: Styles,  Next: Advanced Customizations,  Prev: Permanent Customization,  Up: Customizing Indentation

Styles
======

   Most people only need to edit code formatted in just a few
well-defined and consistent styles.  For example, their organization
might impose a "blessed" style that all its programmers must conform
to.  Similarly, people who work on GNU software will have to use the
GNU coding style on C code.  Some shops are more lenient, allowing some
variety of coding styles, and as programmers come and go, there could
be a number of styles in use.  For this reason, `vhdl-mode' makes it
convenient for you to set up logical groupings of customizations called
"styles", associate a single name for any particular style, and pretty
easily start editing new or existing code using these styles.  This
chapter describes how to set up styles and how to edit your C code
using styles.

* Menu:

* Built-in Styles::
* Adding Styles::
* File Styles::


File: vhdl-mode.info,  Node: Built-in Styles,  Next: Adding Styles,  Up: Styles

Built-in Styles
---------------

   If you're lucky, one of `vhdl-mode''s built-in styles might be just
what you're looking for.  Some of the most common VHDL styles are
already built-in.  These include:

   * `GNU' - the coding style in the IEEE Language Reference Manual.

   If you'd like to experiment with these built-in styles you can simply
type the following in a `vhdl-mode' buffer:

     M-x vhdl-set-style RET.

You will be prompted for one of the above styles (with completion).
Enter one of the styles and hit `RET'.  Note however that setting a
style in this way does *not* automatically re-indent your file.  For
commands that you can use to view the effect of your changes, see *Note
Indentation Commands::.

   Once you find a built-in style you like, you can make the change
permanent by adding a call to your `.emacs' file.  Let's say for
example that you want to use the `IEEE' style in all your files.  You
would add this:

     (defun my-vhdl-mode-hook ()
       ;; use IEEE style for all VHDL code
       (vhdl-set-style "IEEE")
       ;; other customizations can go here
       )
     (add-hook 'vhdl-mode-hook 'my-vhdl-mode-hook)

*Note Permanent Customization::.


File: vhdl-mode.info,  Node: Adding Styles,  Next: File Styles,  Prev: Built-in Styles,  Up: Styles

Adding Styles
-------------

   If none of the built-in styles is appropriate, you'll probably want
to add a new style definition.  Styles are kept in the
`vhdl-style-alist' variable, but you probably won't want to modify this
variable directly.  `vhdl-mode' provides a function, called
`vhdl-add-style', that you can use to easily add new styles or update
existing styles.  This function takes two arguments, a STYLENAME
string, and an association list DESCRIPTION of style customizations.  If
STYLENAME is not already in `vhdl-style-alist', the new style is added,
otherwise the style already associated with STYLENAME is changed to the
new DESCRIPTION.  This function also takes an optional third argument,
which if non-`nil', automatically institutes the new style in the
current buffer.

   The sample `.emacs' file provides a concrete example of how a new
style can be added and automatically set.  *Note Sample .emacs File::.


File: vhdl-mode.info,  Node: File Styles,  Prev: Adding Styles,  Up: Styles

File Styles
-----------

   The Emacs manual describes how you can customize certain variables
on a per-file basis by including a "Local Variable" block at the end of
the file.  So far, you've only seen a functional interface to
`vhdl-mode', which is highly inconvenient for use in a Local Variable
block.  `vhdl-mode' provides two variables that make it easier for you
to customize your style on a per-file basis.

   The variable `vhdl-file-style' can be set to a style name string as
described in *Note Built-in Styles::.  When the file is visited,
`vhdl-mode' will automatically set the file's style to this style using
`vhdl-set-style'.

   Another variable, `vhdl-file-offsets', takes an association list
similar to what is allowed in `vhdl-offsets-alist'.  When the file is
visited, `vhdl-mode' will automatically institute these offets using
`vhdl-set-offset'.  *Note Customizing Indentation::.

   Note that file style settings (i.e. `vhdl-file-style') are applied
before file offset settings (i.e. `vhdl-file-offsets').


File: vhdl-mode.info,  Node: Advanced Customizations,  Prev: Styles,  Up: Customizing Indentation

Advanced Customizations
=======================

   For most users, `vhdl-mode' will support their coding styles with
very little need for customizations.  Usually, one of the standard
styles defined in `vhdl-style-alist' will do the trick.  Sometimes, one
of the syntactic symbol offsets will need to be tweeked slightly, or
perhaps `vhdl-basic-offset' will need to be changed.  However, some
styles require a more advanced ability for customization, and one of the
real strengths of `vhdl-mode' is that the syntactic analysis model
provides a very flexible framework for customizing indentation. This
allows you to perform special indentation calculations for situations
not handled by the mode directly.

* Menu:

* Custom Indentation Functions::
* Other Special Indentations::


File: vhdl-mode.info,  Node: Custom Indentation Functions,  Next: Other Special Indentations,  Up: Advanced Customizations

Custom Indentation Functions
----------------------------

   One of the most common ways to customize `vhdl-mode' is by writing
"custom indentation functions" and associating them with specific
syntactic symbols (see *Note Syntactic Symbols::).  `vhdl-mode' itself
uses custom indentation functions to provide more sophisticated
indentation, for example when lining up selected signal assignments:

     %%% TBD %%%

   In this example, the `statement-cont' syntactic symbol has an offset
of `+', and `vhdl-basic-offset' is 2, so lines 4 through 6 are simply
indented two spaces to the right of line 3.  But perhaps we'd like
`vhdl-mode' to be a little more intelligent so that it offsets the
waveform descriptions relative to the signal assignment operator in
line 3.  To do this, we have to write a custom indentation function
which finds the column of signal assignment operator on the first line
of the statement.  Here is the lisp code (from the `vhdl-mode.el'
source file) that implements this:

     (defun vhdl-lineup-statement-cont (langelem)
       ;; line up statement-cont after the assignment operator
       (save-excursion
         (let* ((relpos (cdr langelem))
            (assignp (save-excursion
                  (goto-char (vhdl-point 'boi))
                  (and (re-search-forward "\\(<\\|:\\)="
                              (vhdl-point 'eol) t)
                   (- (point) (vhdl-point 'boi)))))
            (curcol (progn
                  (goto-char relpos)
                  (current-column)))
            foundp)
           (while (and (not foundp)
               (< (point) (vhdl-point 'eol)))
         (re-search-forward "\\(<\\|:\\)=\\|(" (vhdl-point 'eol) 'move)
         (if (vhdl-in-literal (cdr langelem))
             (forward-char)
           (if (= (preceding-char) ?\()
               ;; skip over any parenthesized expressions
               (goto-char (min (vhdl-point 'eol)
                       (scan-lists (point) 1 1)))
             ;; found an assignment operator (not at eol)
             (setq foundp (not (looking-at "\\s-*$"))))))
           (if (not foundp)
           ;; there's no assignment operator on the line
           vhdl-basic-offset
         ;; calculate indentation column after assign and ws, unless
         ;; our line contains an assignment operator
         (if (not assignp)
             (progn
               (forward-char)
               (skip-chars-forward " \t")
               (setq assignp 0)))
         (- (current-column) assignp curcol))
           )))

Custom indent functions take a single argument, which is a syntactic
component cons cell (see *Note Syntactic Analysis::).  The function
returns an integer offset value that will be added to the running total
indentation for the lne.  Note that what actually gets returned is the
difference between the column that the signal assignment operator is
on, and the column of the buffer relative position passed in the
function's argument.  Remember that `vhdl-mode' automatically adds in
the column of the component's relative buffer position and we don't
want that value added into the final total twice.

   Now, to associate the function `vhdl-lineup-statement-cont' with the
`statement-cont' syntactic symbol, we can add something like the
following to our `vhdl-mode-hook':

     (vhdl-set-offset 'statement-cont 'vhdl-lineup-statement-cont)

   Now the function looks like this after re-indenting (using `C-c
C-q'):

     %%% TBD %%%

   Custom indentation functions can be as simple or as complex as you
like, and any syntactic symbol that appears in `vhdl-offsets-alist' can
have a custom indentation function associated with it.  Note however
that using many custom indentation functions may have a performance
impact on `vhdl-mode'.


File: vhdl-mode.info,  Node: Other Special Indentations,  Prev: Custom Indentation Functions,  Up: Advanced Customizations

Other Special Indentations
--------------------------

   One other variable is available for you to customize `vhdl-mode':
`vhdl-special-indent-hook'.  This is a standard hook variable that is
called after every line is indented by `vhdl-mode'.  You can use it to
do any special indentation or line adjustments your style dictates,
such as adding extra indentation to the port map clause in a component
instantiation, etc.  Note however, that you should not change `point'
or `mark' inside your `vhdl-special-indent-hook' functions.


File: vhdl-mode.info,  Node: Syntactic Symbols,  Next: Frequently Asked Questions,  Prev: Customizing Indentation,  Up: Top

Syntactic Symbols
*****************

   The complete list of recognized syntactic symbols is described in the
`vhdl-offsets-alist' variable.  This chapter will provide some examples
to help clarify these symbols.

   Most syntactic symbol names follow a general naming convention.
When a line begins with a `begin' or `end' keyword, the syntactic
symbol will contain the suffix `-open' or `-close' respectively.

   Usually, a distinction is made between the first line that
introduces a construct and lines that continue a construct, and the
syntactic symbols that represent these lines will contain the suffix
`-intro' or `-cont' respectively.  As a sub-classification of this
scheme, a line which is the first of a particular block construct will
contain the suffix `-block-intro'.

   *<TBD> include the name and a brief example of every syntactic
symbol currently recognized*


File: vhdl-mode.info,  Node: Frequently Asked Questions,  Next: Getting the latest vhdl-mode release,  Prev: Syntactic Symbols,  Up: Top

Frequently Asked Questions
**************************

     *Q.* *How do I re-indent the whole file?*

     *A.* Visit the file and hit `C-x h' to mark the whole buffer. Then
     hit `<ESC> C-\' to re-indent the entire region which you've just
     marked.

     *Q.* *How do I re-indent the entire function?*

     *A.* Hit `<ESC> C-h' to mark the entire function. Then hit `<ESC>
     C-\' to re-indent the entire region which you've just marked.

     *Q.* *How do I re-indent the current block?*

     *A.* First move to the brace which opens the block with `<ESC>
     C-u', then re-indent that expression with `<ESC> C-q'.

     *Q.* *How do I re-indent the current statement?*

     *A.* First move to the beginning of the statement with `<ESC> a',
     then re-indent that expression with `<ESC> C-q'.

     *Q.* *Why doesn't the <RET> key indent the line to where the new
     text should go after inserting the newline?*

     *A.* Emacs' convention is that <RET> just adds a newline, and that
     <LFD> adds a newline and indents it.  You can make <RET> do this
     too by adding this to your `vhdl-mode-hook' (see the sample
     `.emacs' file *Note Sample .emacs File::):

          (define-key vhdl-mode-map "\C-m" 'newline-and-indent)

     This is a very common question. `:-)' If you want this to be the
     default behavior, don't lobby me, lobby RMS!

     *Q.* *I put `(vhdl-set-offset 'statement-cont 0)' in my `.emacs'
     file but I get an error saying that `vhdl-set-offset''s function
     definition is void.*

     *A.* This means that `vhdl-mode' wasn't loaded into your Emacs
     session by the time the `vhdl-set-offset' call was reached, mostly
     likely because `vhdl-mode' is being autoloaded.  Instead of
     putting the `vhdl-set-offset' line in your top-level `.emacs'
     file, put it in your `vhdl-mode-hook', or simply add the following
     to the top of your `.emacs' file:

          (require 'vhdl-mode)

     See the sample `.emacs' file *Note Sample .emacs File:: for
     details.



File: vhdl-mode.info,  Node: Getting the latest vhdl-mode release,  Next: Sample .emacs File,  Prev: Frequently Asked Questions,  Up: Top

Getting the latest `vhdl-mode' release
**************************************

   The best way to be sure you always have the latest `vhdl-mode'
release is to join the `vhdl-mode-announce' mailing list.  If you are a
brave soul, and wish to participate in beta testing of new releases of
`vhdl-mode', you may also join the `vhdl-mode-victims' mailing list.
Send email to the author to join either of these lists.

   The Official `VHDL-Mode' Home Page can be found at
`http://www.geocities.com/SiliconValley/Park/8287/vhdl-mode.html'.


File: vhdl-mode.info,  Node: Sample .emacs File,  Next: Requirements,  Prev: Getting the latest vhdl-mode release,  Up: Top

Sample `.emacs' file
********************

     ;; Here's a sample .emacs file that might help you along the way.  Just
     ;; copy this region and paste it into your .emacs file.  You may want to
     ;; change some of the actual values.

     (defconst my-vhdl-style
       '((vhdl-tab-always-indent        . t)
         (vhdl-comment-only-line-offset . 4)
         (vhdl-offsets-alist            . ((arglist-close    . vhdl-lineup-arglist)
                                           (statement-cont   . 0)
                                           (case-alternative . 4)
                                           (block-open       . 0)))
         (vhdl-echo-syntactic-information-p . t)
         )
       "My VHDL Programming Style")

     ;; Customizations for vhdl-mode
     (defun my-vhdl-mode-hook ()
       ;; add my personal style and set it for the current buffer
       (vhdl-add-style "PERSONAL" my-vhdl-style t)
       ;; offset customizations not in my-vhdl-style
       (vhdl-set-offset 'statement-case-intro '++)
       ;; other customizations
       (setq tab-width 8
             ;; this will make sure spaces are used instead of tabs
             indent-tabs-mode nil)
       ;; keybindings for VHDL are put in vhdl-mode-map
       (define-key vhdl-mode-map "\C-m" 'newline-and-indent)
       )

     ;; the following only works in Emacs 19
     ;; Emacs 18ers can use (setq vhdl-mode-hook 'my-vhdl-mode-hook)
     (add-hook 'vhdl-mode-hook 'my-vhdl-mode-hook)


File: vhdl-mode.info,  Node: Requirements,  Next: Limitations and Known Bugs,  Prev: Sample .emacs File,  Up: Top

Requirements
************

   `vhdl-mode.el' requires `reporter.el' for submission of bug reports.
`reporter.el' is distributed with the latest FSF and XEmacs 19's.
Here is the Emacs Lisp Archive anonymous ftp'ing record for those of
you who are using older Emacsen.


              GNU Emacs Lisp Code Directory Apropos -- "reporter"
     "~/" refers to archive.cis.ohio-state.edu:/pub/gnu/emacs/elisp-archive/

     reporter (2.12)       06-Jul-1994
          Barry A. Warsaw, <[e-mail]>
          ~/misc/reporter.el.Z
          Customizable bug reporting of lisp programs.


File: vhdl-mode.info,  Node: Limitations and Known Bugs,  Next: Mailing Lists and Submitting Bug Reports,  Prev: Requirements,  Up: Top

Limitations and Known Bugs
**************************

   * Re-indenting large regions or expressions can be slow.

   * Use with Emacs 18 can be slow and annoying. You should seriously
     consider upgrading to Emacs 19.


File: vhdl-mode.info,  Node: Mailing Lists and Submitting Bug Reports,  Next: Concept Index,  Prev: Limitations and Known Bugs,  Up: Top

Mailing Lists and Submitting Bug Reports
****************************************

   To report bugs, use the `C-c C-b' (`vhdl-submit-bug-report')
command.  This provides vital information I need to reproduce your
problem.  Make sure you include a concise, but complete code example.
Please try to boil your example down to just the essential code needed
to reproduce the problem, and include an exact recipe of steps needed to
expose the bug.  Be especially sure to include any code that appears
*before* your bug example.

   For other help or suggestions, send a message to
`[e-mail]'.

   Send an add message to `[e-mail]' to get on the
`vhdl-mode-victims' beta testers list where beta releases of
`vhdl-mode' are posted.  Note that you shouldn't expect beta releases
to be as stable as public releases.

   There is also an announce only list where the latest public releases
of `vhdl-mode' are posted.  Send an add message to
`[e-mail]' to be added to this list.


File: vhdl-mode.info,  Node: Concept Index,  Next: Command Index,  Prev: Mailing Lists and Submitting Bug Reports,  Up: Top

Concept Index
*************

* Menu:

* -block-intro syntactic symbols:        Syntactic Symbols.
* -close syntactic symbols:              Syntactic Symbols.
* -cont syntactic symbols:               Syntactic Symbols.
* -intro syntactic symbols:              Syntactic Symbols.
* -open syntactic symbols:               Syntactic Symbols.
* .emacs file:                           Getting Connected.
* Adding Styles:                         Adding Styles.
* Advanced Customizations:               Advanced Customizations.
* announcement mailing list:             Mailing Lists and Submitting Bug Reports.
* basic-offset (vhdl-):                  Customizing Indentation.
* beta testers mailing list:             Mailing Lists and Submitting Bug Reports.
* Built-in Styles:                       Built-in Styles.
* byte compile:                          Getting Connected.
* comment only line:                     Syntactic Analysis.
* custom indentation functions:          Custom Indentation Functions.
* Custom Indentation Functions:          Custom Indentation Functions.
* Customizing Indentation:               Customizing Indentation.
* File Styles:                           File Styles.
* Frequently Asked Questions:            Frequently Asked Questions.
* Getting Connected:                     Getting Connected.
* Getting the latest vhdl-mode release:  Getting the latest vhdl-mode release.
* hooks:                                 Permanent Customization.
* IEEE style:                            Built-in Styles.
* Indentation Calculation:               Indentation Calculation.
* Indentation Commands:                  Indentation Commands.
* Interactive Customization:             Interactive Customization.
* Introduction:                          Introduction.
* Limitations and Known Bugs:            Limitations and Known Bugs.
* local variables:                       File Styles.
* Mailing Lists and Submitting Bug Reports: Mailing Lists and Submitting Bug Reports.
* New Indentation Engine:                New Indentation Engine.
* Other Special Indentations:            Other Special Indentations.
* Permanent Indentation:                 Permanent Customization.
* relative buffer position:              Syntactic Analysis.
* reporter.el:                           Requirements.
* Requirements:                          Requirements.
* Sample .emacs file:                    Sample .emacs File.
* set-offset (vhdl-):                    Customizing Indentation.
* statement-cont syntactic symbol:       Custom Indentation Functions.
* Styles:                                Styles.
* Syntactic Analysis:                    Syntactic Analysis.
* syntactic component:                   Syntactic Analysis.
* syntactic component list:              Syntactic Analysis.
* syntactic symbol:                      Syntactic Analysis.
* Syntactic Symbols:                     Syntactic Symbols.
* TAB:                                   Indentation Calculation.
* vhdl-basic-offset:                     Customizing Indentation.
* vhdl-set-offset:                       Customizing Indentation.


File: vhdl-mode.info,  Node: Command Index,  Next: Key Index,  Prev: Concept Index,  Up: Top

Command Index
*************

   Since all `vhdl-mode' commands are prepended with the string
`vhdl-', each appears under its `vhdl-<thing>' name and its `<thing>
(vhdl-)' name.

* Menu:

* add-style (vhdl-):                     Adding Styles.
* indent-defun (vhdl-):                  Interactive Customization.
* lineup-statement-cont (vhdl-):         Custom Indentation Functions.
* newline-and-indent:                    Frequently Asked Questions.
* set-offset (vhdl-) <1>:                File Styles.
* set-offset (vhdl-):                    Interactive Customization.
* set-style (vhdl-):                     Built-in Styles.
* show-syntactic-information (vhdl-):    Syntactic Analysis.
* submit-bug-report (vhdl-):             Mailing Lists and Submitting Bug Reports.
* vhdl-add-style:                        Adding Styles.
* vhdl-indent-defun:                     Interactive Customization.
* vhdl-lineup-statement-cont:            Custom Indentation Functions.
* vhdl-set-offset <1>:                   File Styles.
* vhdl-set-offset:                       Interactive Customization.
* vhdl-set-style:                        Built-in Styles.
* vhdl-show-syntactic-information:       Syntactic Analysis.
* vhdl-submit-bug-report:                Mailing Lists and Submitting Bug Reports.
* vhdl-version:                          Introduction.


File: vhdl-mode.info,  Node: Key Index,  Next: Variable Index,  Prev: Command Index,  Up: Top

Key Index
*********

* Menu:

* C-c C-b:                               Mailing Lists and Submitting Bug Reports.
* C-c C-o:                               Interactive Customization.
* C-c C-q <1>:                           Frequently Asked Questions.
* C-c C-q <2>:                           Custom Indentation Functions.
* C-c C-q:                               Interactive Customization.
* C-c C-s:                               Syntactic Analysis.
* C-x h:                                 Frequently Asked Questions.
* ESC C-\:                               Frequently Asked Questions.
* ESC C-q:                               Frequently Asked Questions.
* ESC C-u:                               Frequently Asked Questions.
* LFD:                                   Frequently Asked Questions.
* RET:                                   Frequently Asked Questions.
* TAB:                                   Indentation Calculation.


File: vhdl-mode.info,  Node: Variable Index,  Prev: Key Index,  Up: Top

Variable Index
**************

   Since all `vhdl-mode' variables are prepended with the string
`vhdl-', each appears under its `vhdl-<thing>' name and its `<thing>
(vhdl-)' name.

* Menu:

* basic-offset (vhdl-):                  Advanced Customizations.
* echo-syntactic-information-p (vhdl-):  Indentation Calculation.
* file-offsets (vhdl-):                  File Styles.
* file-style (vhdl-):                    File Styles.
* offsets-alist (vhdl-) <1>:             Custom Indentation Functions.
* offsets-alist (vhdl-) <2>:             File Styles.
* offsets-alist (vhdl-) <3>:             Indentation Calculation.
* offsets-alist (vhdl-):                 Syntactic Analysis.
* special-indent-hook (vhdl-):           Other Special Indentations.
* style-alist (vhdl-) <1>:               Advanced Customizations.
* style-alist (vhdl-):                   Adding Styles.
* vhdl-basic-offset:                     Advanced Customizations.
* vhdl-echo-syntactic-information-p:     Indentation Calculation.
* vhdl-file-offsets:                     File Styles.
* vhdl-file-style:                       File Styles.
* vhdl-mode-hook:                        Permanent Customization.
* vhdl-offsets-alist <1>:                Syntactic Symbols.
* vhdl-offsets-alist <2>:                Custom Indentation Functions.
* vhdl-offsets-alist <3>:                File Styles.
* vhdl-offsets-alist <4>:                Indentation Calculation.
* vhdl-offsets-alist:                    Syntactic Analysis.
* vhdl-special-indent-hook:              Other Special Indentations.
* vhdl-style-alist <1>:                  Advanced Customizations.
* vhdl-style-alist:                      Adding Styles.



Tag Table:
Node: Top184
Node: Introduction759
Node: Getting Connected1559
Node: New Indentation Engine4265
Node: Syntactic Analysis5167
Node: Indentation Calculation7730
Node: Indentation Commands10042
Node: Customizing Indentation10223
Node: Interactive Customization12311
Node: Permanent Customization14653
Node: Styles16229
Node: Built-in Styles17214
Node: Adding Styles18487
Node: File Styles19524
Node: Advanced Customizations20634
Node: Custom Indentation Functions21517
Node: Other Special Indentations25294
Node: Syntactic Symbols25955
Node: Frequently Asked Questions26964
Node: Getting the latest vhdl-mode release29143
Node: Sample .emacs File29820
Node: Requirements31446
Node: Limitations and Known Bugs32152
Node: Mailing Lists and Submitting Bug Reports32515
Node: Concept Index33664
Node: Command Index36898
Node: Key Index38344
Node: Variable Index39372

End Tag Table